'\" t
'
' Name:		tpintro.1m
'
' Completed:	18th August, 2003.
'
' Updated:	5th August, 2004.
'
' Purpose:	Introduction to the Tarp commands/features/terms.
'
' Author:	Simon Edwards, Proprius Consulting Ltd.
'
' Version:	@(#)1.1 Original (SE)
'		@(#)1.2 Include information on bundle support (SE)
'
.TH tpintro 1M "5 August 2004" "Linuxha.net"

.SH NAME
tpintro - Introductiion to the Tarp package manager

.SH DESCRIPTION
The purpose of this manual page is to describe the Tarp package manager. 
Tarp - in summary - is a cross platform toolset for allowing global and
per-user package management on a variety of UNIX platforms using only
standard shell facilities.

.SS Why Develop Tarp?
Tarp was actually written for the following reasons:

.TP 4
[1]
The author had a requirement for a simplfied package management system that
could be easily ported to many different UNIX operating systems with little 
effort.
.TP
[2]
A cross-platform packaging format to integrate with the Code Manager
utilities was defined as a Good Thing(tm). A simple Tarball format was
considered just a little primitive.
.TP
[3]
The ability for users to have their own installed packages independent of the
system installed packages. After some early experimentation this was found
to be particularly useful for developers since the package deployment could 
be tested without root access.
.TP
[4]
The ability to support automatic dependency selection both during installation 
and removal of packages. Later versions are likely to be able to probe 
remote resources to meet dependencies to ensure chasing software packages is
simply not necessary.
.TP
[5]
Simply because the author wanted to write one!

.SS Headline Features
The overall aim of the Tarp package manager is to provide a simple manner
of installing and managing currently installed software. A key set of 
requirements were defined and then adhered to. There are many other, more
powerful, package management toolsets around, but none as as simple (in my
opinion).

A summary list of features offered by the currently installed version include:

.TP 4
[1] Standard Package Format
When a Tarp package has been built, as the name suggests, the resulting file
is simply a tar archive file, (which may optionally be compressed). If you do
not have, or do not want to use Tarp package management, then you can
simply extract the files to a temporary directory, and use them as you see fit.

This facility can be used to install Tarp from a Tarp package - you simply
extract the tpinstall script to a temporary directory, and use it to install
script to install the package. 

.TP
[2] Automatic Dependency Management
When installing an item of software the default action is to search for all
necessary dependencies and provide a list of them and install them if
available, and if not, list those that can not be found.

It should be noted that this is not the immediate list - it will recursively
check the dependency requirements as far as possible - depending on the contents
of the specified software depot.

This concept obviously covers package deletion as well, and though it can be
overridden, it will not be possible to remove a package on which other
packages depend without "forcing" it.

Later versions are likely to include the facility to provide a configuration
file of local and remote depots (collections of packages) which are
turned to if a particular dependency can not be found on the local server.

.TP
[3] Package Bundling
The software supports the concept of "depots" - collections of packages
that may be related to one another. When you install software you must specify
a depot to take it from - which might simply be the current directory.

The current software release only supports depots as local directories. However
a directory can contain multiple packages, even different versions of the same
package, or the same package for multiple architectures.

This version also is the first to offer support for package bundles - the
ability to install and manage a series of packages as a single entity -
which makes distribution and management of groups of packages far easier.

Since this is the initial release supporting bundles there are some 
limitations which are explained later in the section \fBREVIEW OF INITIAL
BUNDLE SUPPORT\fP.

.TP
[4] Local Installed Package Databases
Most package management software has been written to manage the complete
environment of software and thus is controlled by the System Administrator.
Although this is fine in most cases, it does not allow normal users to 
manage software in directories over which they have control.

The Tarp package management environment overcomes this problem by allowing
users (all users) to be able to specify the location of the Installed package
database - typically "$HOME/.tarpdb". They are then able to install, list,
check and remove software like the System Administrator.

The default Installed Package Database location is "/var/adm/tarp" - and this
should obviously only be writable by the "root" user.

.TP
[5] Root Directory Override
This feature is closely related to that listed above - it allows the user
during the installation of a package to define the "root" directory for the
package. This may have been specified during the package creation, but can 
always be overridden on the command line.

This is typically used when normal users install software - they set the
\fBTARP_DB\fP environment variable and then ensure that the root directory
is set to there home directory, or maybe a sub-directory, such as
"/home/sedwards/install".

Similarly it is also possible to ensure that the "permissions" settings
for the package are ignored - this is particularly useful for non-root
user installations since you might not want the files to be changed owner
since you might not be able to delete them later!

.TP
[6] Installation and Removal Scripts
It is possible to build a package that can run a script under the following
conditions:

.RS 4
.TP 4
*
Before installation of a package
.TP
*
After installation of a package
.TP
* 
Prior to removal of a package
.TP
*
After the removal of a package
.RE
.TP 4
This version also supports the inclusion of a "checkinstall" script in a
package - which will be used when installing packages from within a bundle - 
since certain packages in the bundle might not be relevant to the current
machihe configuration.

[7] Simple Package Creation
The process of actually creating a package is very straightforward - a simple
(text) configuration file is built and using this a package is defined.

There is currently no concept of the package being "built" - you must prepare
the directories prior to building the package if you want to do such a 
thing.

The recommended approach currently is not to distribute source code - but to
compile it prior to packaging. If this approach is not suitable then
distribute the source and use a post installation script to compile and
install it.

This version also includes a tool allowing built packages to be combined
into bundles, which can then be used to distribute and install multiple 
packages from a single file.

.TP
[8] Operating system and architecture awareness
The package format supports the ability to generate different types
of packages. For example it is possible to tie down a package to ensure
it can only be installed on a particular CPU type as well as operating 
system type. 

It is also possible to create a package that can be installed on any
version or architecture of a particular operation system. Finally completely
"generic" packages can be built - allowing the same package to be deployed
on to any operating system where "Tarp" is available.
these can be installed on any architecture as desired. This is useful when the
package contains no compiled code, for example.

However the default option is to generate a package which is specific to
both the operating system and architecture of the local machine. This means
that only machines of the same type, running the same operating system
can install the package.

Currently the capabilities to match a particular machine, operating system
and architecture are quite limited, though again, this is likely to be
enhanced in later versions, (assuming the simplicity of the Tarp format is
not compromised).

.SH CONCEPTS
Given the simplicity of the package management system this section is
mercifully short. The concepts should easily relate to other package
management toolsets you have used.

.TP 4
.B * \fBPACKAGE\fP
This is the smallest unit that can be installed or removed by Tarp. It is 
simply a Tar archive file containing all the files to installed, (stored in
a relative format), as well as specific information relating to the package - 
such as the verion, architecture, installation scripts etc.
.TP
.B * \fBDEPOT\fP
A depot is a location which contains one or more Tarp packages. Currently the
only supported depot type is a local directory. The directory does not even
need to contain only Tarp packages - it can contain other directories or 
files, (typically files packaged in another format).

Also the Tarp packages in the directory of course do not need to relate
just to the current platform, though of course such packages in a depot
are ignored when you install software from it.

The Tarp commands act on a depot is a collection point for a series of 
packages. For example when you install a package it will look in that
depot for any dependencies that the package you wish to install requires.
.TP
.B * \fBTARGET PLATFORM\fP
The original purpose of this packaging format was to distribute packages
of scripts, (shell, Python, Perl, Tcl, etc) - rather than binary programs. 
Thus the package could potentially be installed on different platforms, 
operating systems and architectures. Such packages can still be built and
are referred to as "architecture and operating system neutral".
.TP
.B * \fBINSTALLED PACKAGE DATABASE\fP
This is simply a directory that the Tarp package management system uses
to store information about any package that is installed. By default the
commands use /var/adm/tarpdb - though this can be overridden using the
environment variable \fBTARP_DB\fP.

By allowing the environment variable to override the location of the 
installed package database normal users able to use package management to
deliver software into directories for which they have control. For a normal
user the recommended setting of the \fBTARP_DB\fP environment variable is
"/home/user/.tarpdb".
.TP
.B * \fBPACKAGE INSTALLATION STATES\fP
It is important to understand the different states a package can appear
in. This information is typically shown when using the \fItplist(1M)\fP
command.
.RS 4
.TP 12
.B Committed
This is the standard state in which a package will appear after using the
standard installation options on the \fItpinstall(1M)\fP command. This state
indicates the package is installed and working as expected.
.TP
.B Installed
This is an intermediate state used during installation of a package - though
it can be left in this state if you wish. In this state you will not be able
to update the package without moving to \fBCommitted\fP state first.

The advantage of leaving a package in this state is that if you remove it, any
files that were over written during the installation will be restored. 
.TP
.B Removing
This status is used during the initial stages of removal of a package. If
the removal script is killed off when the package is in this status it will
still actually be usable. Use of the \fItpfix(1M)\fP utility can be used
to restore the package to its original state.
.TP
.B Removed
In the later stages of package removal this status is used to indicate that
if the packge removal is killed off, then the \fItpfix(1M)\fP utility will
complete the removal of this package.
.TP
.B Broken
This is a temporary status used during the installation of a package indicating
that the package installation is not yet complete. In this case use of the 
\fItpfix(1M)\fP will remove the package back to a clean installation.
.RE

.SH COMMAND SUMMARY
The Tarp environment only offers a very limited set of commands, again
reflecting the simple nature of the format.

.TS
l l.
Command	Purpose
=
tpinstall	Installs a Tarp package
tpremove	Removes a Tarp package
tplist	List Tarp packages (installed or in a depot)
tpchk	Check validity of installed package
tppkg	Create a Tarp package
tpfix	Clean up packages in an invalid state
tpbundle	Create or update a bundle of packages
.TE

.SH LIMITATIONS
The whole point of this set of utilities is to provide a straightforward
method of installing and managing packages. Due to this design constraint
there are some obvious limitations compared to more advanced package
management suites. The list below is simply some of the more obvious - 
including information on whether they may be addressed in later releases.

.TP 4
[1]
Currently there is no support for Ex-dependencies. That is allowing a 
package to be installed on if a specified package is not installed. Although
not used often can be very useful when packaging a series of related and
occasionally over-lapping packages.

This will be addressed in a later version of the software.
.TP
[2]
When installing a package it is not possible to give it more than a single
depot to scan for dependencies checks. It might be useful to provide a list
of depots (for example a local directory, and then a remote one if the first
fails to match a dependency).

As previously stated this will be addressed in a later software revision,
but is not likely to appear soon.
.TP
[3]
Currently the only type of depot supported is a local directory. Some other
package manages allow anonymous FTP sources to be referenced, or even
directories on other machines.

It is likely that FTP and HTTP depots will be supported in the future via
the use of wrapping utilities such as \fIwget\fP or \fIcurl\fP. Support for
remote directories is further down on the list of improvements, and would
probably require SSH authentication to ensure adequate security.
.TP
[4]
Alhough package file checksumming is implemented - and thus the \fItpchk(1M)\fP
utility, the algorithm used depends on the platform - where \fImd5sum(1)\fP 
command is not available \fIcksum(1)\fP is the fall-back, and thus is
not as secure.

Currently the security information regarding the files kept does not
include other information such as permissions, owner, group and 
modification times.

Although adding this level of checks is not difficult it is not likely to be
added - use something along the lines of TripWire or a similar product instead.
.TP
[5]
Package matching - currently when you install a named package from a depot
you will always get the package with the highest version number, (which
in most cases is what you desire). Unfortunately there is no way of specifying
the particular version of a package to install - hence you might need to copy
the particular file out of the depot to somewhere no other versions exist and
install from that location.

This is probably one of the more critical features I believe to be missing
and thus is most likely to be implemented in the not too distant future.

.SH SEE ALSO
.BR tpbundle(1M),
.BR tpinstall(1M),
.BR tpremove(1M),
.BR tplist(1M),
.BR tpchk(1M),
.BR tppkg(1M),
.BR tpfix(1M).

.SH NOTES
The Tarp series of utilities where written to Integrate with the Code
Manager utilities, though can be used independantly. These utilities have
been developed on Linux and HP-UX simultaneously, and should require
very little, if any, porting to enable them to function on other platforms.

